This vignette exemplifies how to create Spatial Annotations in SPATA2.

1. Spatial Annotations in General

Spatial Annotations represent annotations for spatial data. The concept allows users to define and store polygons that outline areas of interest within images or datasets. The outlines, in turn, can be used as spatial references to visualize feature expression as a function of distance to areas that are potential biological forces. Generally speaking, a spatial annotation simplay require a polygon. SPATA2 implements three concepts of Spatial Annotations: (Spatial) Image Annotations, (Spatial) Group Annotations and (Spatial) Numeric Annotations.

2. Image Annotations

This section uses the sample UKF313T as an example. You can download the raw data set here and the processed SPATA2 object here.

library(SPATA2)

# assuming that you have downloaded or created the SPATA2 object using the raw data
# replace the directory accordingly

object_t313 <- loadSpataObject("my/path/to/object_UKF313T.RDS")

plotImage(oject_t313)

# uses the results of computeMetaFeatures(), counts are heavily right skewed -> transform
plotSurface(object_t313, color_by = "n_counts_rna", transform_with = log10) + 
  labs(color = "counts\n(log10)")
Fig.1 The sample UKF313T with multiple prominent necrotic areas.Fig.1 The sample UKF313T with multiple prominent necrotic areas.

Fig.1 The sample UKF313T with multiple prominent necrotic areas.

Image annotations are represented by the S4 class ImageAnnotation, which is designed to capture spatial annotations by outlining areas of interest on images. It provides a flexible framework for creating annotations that visually highlight specific regions within images, such as histological structures, cellular patterns, or other histo-morphological features in images. It can be interactively created with the createImageAnnotations() function. This function lets you access an interactive application in which you can encircle the structure or area you want to annotate.

object_t313 <- createImageAnnotations(object_t313)
Fig.2 A gif that exemplifies the creation of an image annotation by encircling the necrotic area on the edge of the tissue. The annotation is accordingly named 'necrotic_edge'.

Fig.2 A gif that exemplifies the creation of an image annotation by encircling the necrotic area on the edge of the tissue. The annotation is accordingly named ‘necrotic_edge’.

The left plot Interaction is where the magic happens. The right plot is used for orientation if you want to zoom in and out. Double click on the left image to start the drawing process. Double click again to stop drawing. If you are using drawing mode Single click on ‘Highlight’ to highlight the encircled area, enter the tags you want to tag the annotation with, enter the ID with which you want to name the annotation and click on ‘Add Image Annotation’. If you are in drawing mode Multiple stopping the drawing immediately highlights the encircled area. This allows to quickly encircle multiple structures of the same kind that are tagged with the same tags (e.g. multiple small vessel). The tab on the right called ‘Added Image Annotations’ allows to visualize all image annotations saved so far. Make sure to click on ‘Close application’ to return the SPATA2 object containing the results.

# results are stored in the processed object that can be downloaded 
plotSpatialAnnotations(
  object = object_t313,
  ids = c("necrotic_area", "necrotic_edge", "necrotic_edge2"), 
  nrow = 1, 
  unit = "px", 
  fill = NA
  )
Fig.3 Example image annotations highlighting necrotic areas.

Fig.3 Example image annotations highlighting necrotic areas.

3. Numeric Annotations

This section uses the sample UKF275T as an example. You can download the raw data set here and the processed SPATA2 object here.

library(SPATA2)

# assuming that you have downloaded or created the SPATA2 object using the raw data
# replace the directory accordingly
object_t275 <- loadSpataObject("my/path/to/object_UKF275T.RDS")

# plot sample 
plotImage(object_t275)

plotSurface(object_t313, color_by = "HM_HYPOXIA") 
# plot sample 
plotImage(object_t275)

plotSurface(object_t275, color_by = "HM_HYPOXIA")
Fig.4 Image and hypoxic area of sample UKF275T.Fig.4 Image and hypoxic area of sample UKF275T.

Fig.4 Image and hypoxic area of sample UKF275T.

Numeric annotations are designed to represent the spatial extent of data points, such as cells or barcoded spots, by filtering and outlining them according to their values for a specific numeric variable. This is particularly suitable for creating annotations that highlight areas of interest based on continuous characteristics like gene expression or other numeric attributes derived from spatial multi-omic datasets. SPATA2 allows to annotate space based on numeric variables automatically using createNumericAnnotations(). For more details on how to manipulate the way the areas are annotated, please refer to the documentation via ?createNumericAnnotations.

object_t275 <- 
  createNumericAnnotations(
    object = object_t275, 
    variable = "HM_HYPOXIA", 
    threshold = "kmeans_high", 
    id = "hypoxic_ann" 
  )

# note that the specified id is suffixed with a number 
# this is because multiple annotations could potentially be created
getSpatAnnIds(object_t275)
## [1] "hypoxic_ann_1"
# plot the outline
hypoxic_ann_outline <- ggpLayerSpatAnnOutline(object_t275, ids = "hypoxic_ann_1")

plotImage(object_t275) + 
  hypoxic_ann_outline

plotSurface(object_t275, color_by = "HM_HYPOXIA") + 
  hypoxic_ann_outline
Fig.5 Creating a spatial annotation based on high expression of hypoxia related genes.Fig.5 Creating a spatial annotation based on high expression of hypoxia related genes.

Fig.5 Creating a spatial annotation based on high expression of hypoxia related genes.

3. Group Annotations

This section uses the sample UKF275T as an example. You can download the raw data set here and the processed SPATA2 object here.

library(SPATA2)

# assuming that you have downloaded or created the SPATA2 object using the raw data
# replace the directory accordingly
object_t275 <- loadSpataObject("my/path/to/object_UKF275T.RDS")

# plot sample 
plotImage(object_t275)

plotSurface(object_t313, color_by = "bayeses_space") 
# plot sample 
plotImage(object_t275)

plotSurface(object_t275, color_by = "bayes_space")
Fig.6 Image and bayes space clustering results of sample UKF275T.Fig.6 Image and bayes space clustering results of sample UKF275T.

Fig.6 Image and bayes space clustering results of sample UKF275T.

Group Annotations are designed to represent the spatial extent of data points, such as cells or barcoded spots, by filtering and outlining them based on predefined groups. This allows for the creation of annotations that highlight specific spatial clusters, areas, or patterns identified through grouping techniques. It provides a means to focus on regions of interest within spatial multi-omic datasets using predefined categorizations. To create such spatial annotations use the function createGroupAnnotations(). For more details on how to manipulate the way the areas are annotated, please refer to the documentation via ?createGroupAnnotations.

object_t275 <- 
  createGroupAnnotations(
    object = object_t275, 
    grouping = "bayes_space", 
    group = "1",
    id = "bspace1" 
  )

# note that the specified id is suffixed with a number 
# this is because multiple annotations could potentially be created
getSpatAnnIds(object_t275)
## [1] "hypoxic_ann_1" "bspace1_1"
# plot the outline
cluster_ann_outline <- ggpLayerSpatAnnOutline(object_t275, ids = "bspace1_1")

plotImage(object_t275) + 
  cluster_ann_outline

plotSurface(object_t275, color_by = "bayes_space") + 
  cluster_ann_outline
Fig.7 Creating a spatial annotation based on cluster results.Fig.7 Creating a spatial annotation based on cluster results.

Fig.7 Creating a spatial annotation based on cluster results.